Release 10.1A: OpenEdge Development:
Progress 4GL Reference

NEW statement

Creates an object instance of a class, and assigns an object reference for the instance to a variable. You access a class object instance, as well as its data members and methods, using its associated object reference variable.

Note: The application is responsible for deleting the class object instance using the DELETE OBJECT statement. If the variable that contains the object reference for the instance goes out of scope before you delete the object instance, the instance remains in memory without an object reference.

Syntax\

object-reference = NEW type-name ( [ parameter [, parameter ] ... ] ) [ NO-ERROR ].

object-reference

The name of the variable to contain the object reference for the new class object instance. You use this object reference variable to access the class object instance, and its PUBLIC data members and methods.

To define an object reference variable for a class object instance, use the DEFINE VARIABLE statement with the CLASS option. For more information, see the DEFINE VARIABLE statement reference entry in this book.

type-name

A character string that specifies the type name of the class. Specify a class type name using the package.class-name syntax as described in the Type-name syntax reference entry in this book.

The class-name must specify one of the following:

The same class that was specified in the object reference variable definition.
A subclass of the class specified in the object reference variable definition.
A class that implements the interface specified in the object reference variable definition.

( parameter [, parameter ] ... )

Specifies one or more parameters to pass to the constructor method defined for the class. You must provide the parameters identified by the constructor method, and the parameters must match with respect to the number, data type, and mode.

For the parameter passing syntax, see the Parameter passing syntax reference entry in this book.

For information about defining a constructor method for a class, see the CONSTRUCTOR statement reference entry in this book.

NO-ERROR

Suppresses any errors that occur during the invocation of the constructor for the class, or any class in the inherited class hierarchy, while attempting to create the class object instance or its inherited class hierarchy. For example:

The class definition file for the class, a super class, or an interface could not be found.
The class definition file for the class, a super class, or an interface could not be compiled.
The run-time parameters of the constructor for the class, or a constructor for a class in the inherited class hierarchy, are not compatible.

When Progress encounters one of these errors, and the constructor method cannot create the class object instance or its inherited class hierarchy, Progress raises the ERROR condition on the NEW statement and sets the object reference to the Unknown value (?).

After the NEW statement completes, you can check the ERROR-STATUS system handle for information about errors that have occurred. For more information, see OpenEdge Getting Started: Object-oriented Programming .

Example

The following example shows the definition of a variable to contain the object reference for a new class object instance:

DEFINE VARIABLE myCustObj AS CLASS acme.myObjs.CustObj NO-UNDO. myCustObj = NEW acme.myObjs.CustObj ( ).

Notes

When you create an object instance of a class, Progress invokes the constructor for the class, and the constructor for each class in its inherited class hierarchy. At this time, the object instance gets its own copy of the data members defined in the class and all classes in its inherited class hierarchy. In addition, the object instance is added to the list of valid object instances referenced by the FIRST-OBJECT and LAST-OBJECT attributes of the SESSION system handle.
To access PUBLIC data members, qualify the data member names with their associated object reference using the following syntax:

object-reference:data-member-name

You cannot access PRIVATE or PROTECTED data members using an object reference. If you want to make these data members available, you must provide PUBLIC methods to do so.

To access PUBLIC methods, qualify the method names with their associated object reference using the following syntax:

object-reference:method-name( [ parameter [, parameter ] ... ] ).

You cannot access PRIVATE or PROTECTED methods using an object reference.

You can use an object reference for a class object instance as a parameter or return type for methods, internal and external procedures, and user-defined functions. You can also assign an object reference to a temporary table field defined as a Progress.Lang.Object; but you cannot assign an object reference to a field in a database table. For more information, see OpenEdge Getting Started: Object-oriented Programming .
You cannot pass an object reference as a parameter to an AppServer; nor can you pass a temporary table containing an object reference field as a parameter to an AppServer.
A class object instance is not associated with a handle. Thus, you cannot use a class in any statement or function that returns a value of type HANDLE, and you cannot pass a procedure handle to a method expecting an object reference.
You can assign one object reference variable to another object reference variable when the destination object reference (on the left side of the assignment) is defined for the same class, a super class, or an interface of the object reference being assigned (on the right side of the assignment). The destination object reference retains its class type. When you assign an object reference for a super class defined higher in the class hierarchy (on the right side of the assignment) to an object reference for a subclass defined lower in the class hierarchy (on the left side of the assignment), you must cast the object reference being assigned by using the CAST function. In any case, the assignment results in a copy of the object reference, which points to the same object instance, not a copy of the associated object instance. For more information about the CAST function, see the CAST function reference entry in this book.
You can compare two object references for equality using the EQ or = operator, which determines if two object references are referencing the same object instance. Two object references can be equal even if you defined them for different classes in the class hierarchy. Two object references are also equal if they are both the Unknown value (?).
You can use the Equals( ) method in the Progress.Lang.Object class to compare the data members of two object references, as long as this class provides an implementation of the Equals( ) method.

See also

CAST function, CLASS statement, CONSTRUCTOR statement, DEFINE VARIABLE statement, FIRST-OBJECT attribute, FUNCTION statement, LAST-OBJECT attribute, METHOD statement